.\" SPDX-License-Identifier: CC-BY-SA-4.0 or-later
.\" SPDX-FileCopyrightText: 2021-2024 grommunio GmbH
.TH autodiscover 7 "" "Gromox" "Gromox admin reference"
.SH Name
autodiscover \(em AutoDiscover protocols
.SH Description
.PP
AutoDiscover is a HTTP-based discovery protocol, originally introduced for
Exchange 2007, that helps users configure
their email client settings automatically. The MS-OXDSCLI specification
speaks about locating such AutoDiscover service, the MS-OXDISCO specification
speaks about the XML exchange between such a service and a client. These terms
are herein used to avoid ambiguity in the "AD" acronym (ActiveDirectory).
.PP
Autodiscover V2 is not an improved version, it is an extra layer that warrants
a disgruntled remark about questionable protocol design. Locating the
AutoDiscover server still happens via DNS or AD-SCP query. The V2 request
contains the user identity and the name of a next-level protocol that the
client seeks, e.g. "ActiveSync", "EWS" or "AutoDiscoverV1". The response is now
a JSON document and generally contains just one URL, namely for the service
sought. Indeed there is no way to obtain MAPI, IMAP or SMTP information in
Autodiscover V2.
.PP
Note that Autodiscover is not used exclusively by Microsoft Outlook,
Autodiscover is the main discovery protocol for any EAS-enabled device and
application, such as Apple iOS, Android and other applications.
.SH OXDSCLI summary
Clients collect one or more AutoDiscover URLs and make HTTP POST requests to
those endpoints to request server configuration. Among the methods that appear
in the wild:
.IP \(bu 4
Using an URL from a previous successful run.
.IP \(bu 4
Performing a DNS TXT lookup on the domain name to check for the presence of a
Microsoft 365 account identifier and, if found, using the URL
<\fBhttps://outlook.office365.com/autodiscover/autodiscover.xml\fP>.
.IP \(bu 4
When joined to an NT Domain/ActiveDirectory, performing an LDAP lookup for
service connection points (SCP), i.e. objects matching
"(&(objectClass=serviceConnectionPoint)
(serviceClassName=ms-Exchange-AutoDiscover-Service))", and using the URLs
obtained from "serviceBindingInformation" attributes.
.IP \(bu 4
"Root domain" method: Constructing a string based on the user's e-mail address
(e.g. u@example.com),
<\fBhttps://\fIexample.com\fP\fB/autodiscover/autodiscover.xml\fP>.
.IP \(bu 4
"AutoDiscover domain" method: Constructing a string based on the user identity,
<\fBhttps://autodiscover.\fP\fIexample.com\fP\fB/autodiscover/autodiscover.xml\fP>.
.IP \(bu 4
Performing a DNS lookup of the name \fB_autodiscover._tcp.\fP\fIdomain\fP of
record type SRV, and from the response data, constructing the string
\fBhttps://\fP\fIrdata\fP[\fB:\fP\fIport\fP]\fB/autodiscover/autodiscover.xml\fP.
.IP \(bu 4
Utilizing an unspecified "local mechanism" method. (might be the same
as using lastrun URL?)
.IP \(bu 4
"Redirect" method: Performing an unauthenticated HTTP GET request to
<\fBhttp://autodiscover.\fP\fIdomain\fP\fB/autodiscover/autodiscover.xml\fP,
and upon receiving a HTTP 302 response, using the URL in the "Location:"
response header for AutoDiscover.
.PP
Gromox recommends that administrators employ the AutoDiscover Domain method,
i.e. add a \fBautodiscover.\fP\fIdomain.com\fP entry to their DNS zones. This
is beneficial over the root domain method, because the host serving up e.g. a
company's website need not be taught about autodiscover paths. For
\fBautodiscover.\fP\fIdomain.com\fP, either an AAAA/A pair \fBor\fP CNAME
resource record can be used. Split-horizon DNS systems \fBmust\fP publish the
autodiscover DNS record(s) in the publicly visible set. The AutoDiscover URL
must equally be reachable from any network segment where access is expected
from \(em if need be, set up HTTP reverse proxies.
.SH OXDISCO summary
When a user sets up a new email account or changes their existing email client
settings, the email client sends an Autodiscover request to the Autodiscover
server. The Autodiscover request is an HTTP POST request that contains the
user's email address. The Autodiscover server then responds with an XML
response that contains the necessary configuration settings.
.PP
The Autodiscover XML response contains information such as
.IP \(bu 4
the list of supported mail protocols and transports (e.g. MSRPC/RPCH/MAPIHTTP,
IMAP, SMTP, etc.)
.IP \(bu 4
the connection parameters for those (e.g. name of the home server, HTTP
endpoint URLs)
.IP \(bu 4
for MAPI, any extra mailboxes that should be opened unconditionally (e.g.
delegators, public folder)
.PP
The email client uses this information to configure the user's email account
automatically.
.SH gromox-dscli notes
The gromox\-dscli(8) utility can be used to diagnose problems with AutoDiscover
from a command line prompt.
.PP
gromox-dscli's probes and their order is: RootDomain, AutoDiscoverDomain, SRV.
.SH Outlook notes
When Outlook is running, there is an Outlook icon in the Windows taskbar's
notification area. By pressing Ctrl+RightMouseBtn, a service menu can be
brought up, which offers a "Test AutoDiscover" command for diagnosing problems
from Windows. Known bugs: The dialog may ignore the contents of the password
field and instead use a saved password or SSO, leading to potentially
unanticipated authentication successes or failures. If in doubt, use
gromox-dscli.
.PP
When an AutoDiscover response contains broken information (e.g. unreachable
endpoints due to a faulty oxdisco_exonym setting on the server), Outlook may
refuse to open mailboxes and the application may exit prematurely. AutoDiscover
responses are cached on disk under `%LOCALAPPDATA%/Microsoft/Outlook/* -
Autodiscover.xml` and/or `%LOCALAPPDATA%/Microsoft/Outlook/16/AutoD.*.xml` and
can be deleted/diagnosed as needed.
.PP
Outlook's probes and primary order: TXT, LDAP-SCP, RootDomain,
AutoDiscoverDomain, SRV, Local, Redirect. Secondary order observed: TXT, LDAP,
RootDomain, AutoDiscoverDomain, Local, Redirect, SRV.
.PP
Individual probes can be disabled via Windows Registry in
.IP \(bu 4
HKEY_CURRENT_USER\\Software\\Microsoft\\Office\\16.0\\Outlook\\AutoDiscover
.PP
and/or
.IP \(bu 4
HKEY_CURRENT_USER\\Software\\Policies\\Microsoft\\Office\\16.0\\Outlook\\AutoDiscover,
.PP
by setting one or more of
.IP \(bu 4
ExcludeLastKnownGoodURL=DWORD:1
.IP \(bu 4
ExcludeExplicitO365Endpoint=DWORD:1
.IP \(bu 4
EnableOffice365ConfigService=DWORD:0
.IP \(bu 4
ExcludeScpLookup=DWORD:1
.IP \(bu 4
ExcludeHttpsRootDomain=DWORD:1
.IP \(bu 4
ExcludeHttpsAutoDiscoverDomain=DWORD:1
.IP \(bu 4
ExcludeSrvRecord=DWORD:1
.IP \(bu 4
ExcludeHttpRedirect=DWORD:1
.PP
as desired. For the Group Policy editor, ADMX template and ADML
language packs are available from
<https://www.microsoft.com/en-us/download/details.aspx?id=49030>.
.PP
When a DNS zone is M365-enabled, Outlook opens a mini browser window for
authenticating with M365. To prevent this, you can set
ExcludeExplicitO365Endpoint=1 as described.
.PP
Outlook stops probing after the first successful AutoDiscover HTTP POST
request. A non-responsive AutoDiscovery server (firewall DROP policy, or TCP
RST) is treated the same as a 404 Not Found response.
.PP
Known bugs: Outlook ignores the port number in the DNS SRV response. Outlook
and/or the Windows HTTP libraries also erroneously show a warning popup
whenever the hostname in the SRV result does not match the e-mail domain (even
under MS Exchange). Redirection is the key idea of an SRV record and, as far as
security considerations go, is no more significant than following a CNAME-typed
autodiscover.example.com record.
.PP
Outlook re-runs AutoDiscover periodically in the background. This can cause
popups such as re-authentication or SRV warnings (particularly after a
temporary outage).
.SH Testing scenarios
To force using a particular Autodiscover server in Windows, such as when Gromox
is run in a development environment with a fake domain,
c:\\windows\\system32\\drivers\\etc\\hosts can be populated with a static entry
for \fBautodiscover.\fP\fIexample.com\fP to get that particular scenario
working.
.SH See also
\fBgromox\fP(7), \fBautoconfig\fP(7), \fBautodiscover\fP(4gx)
